﻿/**
 * @file circulardial.h
 * @brief 定义了 CircularDial 类，用于绘制圆形仪表盘
 * @date 2025-08-07
 */

#ifndef CIRCULARDIAL_H
#define CIRCULARDIAL_H

#include <QLabel>
#include <QPropertyAnimation>
/**
 * @class CircularDial
 * @brief 圆形仪表盘类，用于显示动态仪表盘界面
 */
class CircularDial : public QWidget
{
    Q_OBJECT                                                                                // Qt 对象宏，用于信号和槽机制
    Q_PROPERTY(float DialValue READ fDialValue WRITE setFDialValue NOTIFY DialValueChanged) // 定义动态属性 DialValue

public:
    /**
     * @brief 构造函数，初始化圆形仪表盘
     * @param parent 父窗口指针，默认为 nullptr
     */
    explicit CircularDial(QWidget* parent = Q_NULLPTR);

    /**
     * @brief 获取低值阈值
     * @return 当前低值阈值
     */
    int nLow() const;

    /**
     * @brief 设置低值阈值
     * @param nLow 新的低值阈值
     */
    void setNLow(int nLow);

    /**
     * @brief 获取高值阈值
     * @return 当前高值阈值
     */
    int nHigh() const;

    /**
     * @brief 设置高值阈值
     * @param nHigh 新的高值阈值
     */
    void setNHigh(int nHigh);

    /**
     * @brief 获取最大值
     * @return 当前最大值
     */
    int nMax() const;

    /**
     * @brief 设置最大值
     * @param nMax 新的最大值
     */
    void setNMax(int nMax);

    /**
     * @brief 获取格式化字符串
     * @return 当前格式化字符串
     */
    QString strFormat() const;

    /**
     * @brief 设置格式化字符串
     * @param strFormat 新的格式化字符串
     */
    void setStrFormat(const QString& strFormat);

    /**
     * @brief 激活仪表盘动画
     */
    void active();

    /**
     * @brief 将仪表盘恢复到正常状态
     */
    void normal();

    /**
     * @brief 获取当前仪表盘值
     * @return 当前仪表盘值
     */
    float fDialValue() const;

    /**
     * @brief 设置仪表盘值
     * @param fDialValue 新的仪表盘值
     */
    void setFDialValue(float fDialValue);

signals:
    void DialValueChanged(); // 💡 与 Q_PROPERTY 中的 NOTIFY 对应

private:
    /**
     * @brief 重写绘制事件，绘制仪表盘
     * @param event 绘制事件对象
     */
    void paintEvent(QPaintEvent* event) override;

    /**
     * @brief 绘制仪表盘背景
     * @param painter 绘图对象
     */
    void paintBg(QPainter& p);

private:
    int m_nLow;                              // 低值阈值
    int m_nHigh;                             // 高值阈值
    int m_nMax;                              // 最大值
    float m_fDialValue;                      // 当前仪表盘值
    bool m_bNeedRefreshBg;                   // 是否需要刷新背景
    QFont m_iconFont;                        // 图标字体
    QPropertyAnimation* m_pAnimationOpacity; // 动画对象
    QString m_strFormat;                     // 格式化字符串
    QPixmap m_pixBg;                         // 背景图像
};

#endif // CIRCULARDIAL_H
